<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>fstat</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_005_302">&nbsp;</a>NAME</h4><blockquote>
fstat - get file status
</blockquote><h4><a name = "tag_000_005_303">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="systypes.h.html">sys/types.h</a>&gt;
#include &lt;<a href="sysstat.h.html">sys/stat.h</a>&gt;

int fstat(int <i>fildes</i>, struct stat *<i>buf</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_005_304">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>fstat()</i>
function obtains information about an open file associated with the file
descriptor
<i>fildes</i>,
and writes it to the area pointed to by
<i>buf.</i>
<p>
If _XOPEN_REALTIME is defined
and has a value other than -1, and
<i>fildes</i>
references a shared memory object,
the implementation need update in the
<b>stat</b>
structure pointed to by the
<i>buf</i>
argument only the
<i>st_uid</i>,
<i>st_gid</i>,
<i>st_size</i>,
and
<i>st_mode</i>
fields, and only the
S_IRUSR,
S_IWUSR,
S_IRGRP,
S_IWGRP,
S_IROTH,
and S_IWOTH file permission bits need be valid.
<p>
The
<i>buf</i>
argument is a pointer to a
<b>stat</b>
structure, as defined in
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>,
into which information is placed concerning the file.
<p>
The structure members
<b>st_mode</b>,
<b>st_ino</b>,
<b>st_dev</b>,
<b>st_uid</b>,
<b>st_gid</b>,
<b>st_atime</b>,
<b>st_ctime</b>
and
<b>st_mtime</b>
will have meaningful values for all file types defined in this document.
The value of the member
<b>st_nlink</b>
will be set to the number of links to the file.
<p>
An implementation that provides additional or alternative file access control
mechanisms may, under implementation-dependent conditions, cause
<i>fstat()</i>
to fail.
<p>
The
<i>fstat()</i>
function updates any time-related fields as described in
<b>File Times Update</b>
(see the <b>XBD</b> specification, <a href="../xbd/charset.html"><b>Character Set</b>&nbsp;</a>),
before writing into the
<i>stat</i>
structure.
</blockquote><h4><a name = "tag_000_005_305">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion, 0 is returned.  Otherwise, -1 is returned and
<i>errno</i>
is set to indicate the error.
</blockquote><h4><a name = "tag_000_005_306">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>fstat()</i>
function will fail if:
<dl compact>

<dt>[EBADF]<dd>
The
<i>fildes</i>
argument is not a valid file descriptor.

<dt>[EIO]<dd>
An I/O error occurred while reading from the file system.

<dt>[EOVERFLOW]<dd>
The file size in bytes or the number of blocks allocated to the file
or the file serial number cannot be represented correctly in the
structure pointed to by 
<i>buf</i>.

</dl>
<p>
The
<i>fstat()</i>
function may fail if:
<dl compact>

<dt>[EOVERFLOW]<dd>
One of the values is too large to store into the structure pointed to by the
<i>buf</i> argument.

</dl>
</blockquote><h4><a name = "tag_000_005_307">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_308">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_309">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_005_310">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="lstat.html">lstat()</a></i>,
<i><a href="stat.html">stat()</a></i>,
<i><a href="sysstat.h.html">&lt;sys/stat.h&gt;</a></i>,
<i><a href="systypes.h.html">&lt;sys/types.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
Derived from Issue 1 of the SVID.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>

